Jido.Plugin.Schedules (Jido v2.2.0)

View Source

Utilities for expanding and managing plugin schedules.

This module handles:

  • Expanding schedule declarations from plugin manifests
  • Generating unique job IDs namespaced to plugin instances
  • Generating signal types for schedule triggers
  • Managing timezone configuration

Schedule Formats

Schedules can be specified in several formats:

  • {"*/5 * * * *", ActionModule} - Simple schedule with default timezone
  • {"*/5 * * * *", ActionModule, tz: "America/New_York"} - With timezone
  • {"*/5 * * * *", ActionModule, signal: "custom.signal"} - Custom signal type

Signal Type Generation

By default, schedule signal types are auto-generated as: "{route_prefix}.__schedule__.{action_name}"

For example, a plugin with routeprefix "slack" and action RefreshToken would generate signal type "slack._schedule.refresh_token".

Custom signal types can be specified with the :signal option.

Job ID Namespacing

Job IDs are namespaced as tuples to ensure uniqueness across plugin instances: {:plugin_schedule, state_key, ActionModule}

Summary

Types

schedule_spec()

Represents an expanded schedule specification.

Functions

expand_schedules(instance)

Expands schedules from a plugin instance.

schedule_route_priority()

Returns the default priority for schedule-generated routes.

schedule_routes(instance)

Generates routes for schedule signal types.

Types

schedule_spec()

@type schedule_spec() :: %{
  cron_expression: String.t(),
  action: module(),
  job_id: {:plugin_schedule, atom(), module()},
  signal_type: String.t(),
  timezone: String.t()
}

Represents an expanded schedule specification.

Functions

expand_schedules(instance)

@spec expand_schedules(Jido.Plugin.Instance.t()) :: [schedule_spec()]

Expands schedules from a plugin instance.

Takes a plugin instance and returns expanded schedule specifications with unique job IDs and auto-generated signal types.

Input Formats

  • {"*/5 * * * *", ActionModule} - Simple with default timezone
  • {"*/5 * * * *", ActionModule, tz: "America/New_York"} - With timezone
  • {"*/5 * * * *", ActionModule, signal: "custom.signal"} - Custom signal

Examples

iex> instance = Instance.new(SlackPlugin)  # route_prefix: "slack"
iex> expand_schedules(instance)
[
  %{
    cron_expression: "*/5 * * * *",
    action: SlackActions.RefreshToken,
    job_id: {:plugin_schedule, :slack, SlackActions.RefreshToken},
    signal_type: "slack.__schedule__.refresh_token",
    timezone: "Etc/UTC"
  }
]

iex> instance = Instance.new({SlackPlugin, as: :support})
iex> expand_schedules(instance)
[
  %{
    cron_expression: "*/5 * * * *",
    action: SlackActions.RefreshToken,
    job_id: {:plugin_schedule, :slack_support, SlackActions.RefreshToken},
    signal_type: "support.slack.__schedule__.refresh_token",
    timezone: "Etc/UTC"
  }
]

schedule_route_priority()

@spec schedule_route_priority() :: integer()

Returns the default priority for schedule-generated routes.

schedule_routes(instance)

@spec schedule_routes(Jido.Plugin.Instance.t()) :: [{String.t(), module(), keyword()}]

Generates routes for schedule signal types.

Schedule signal types need routes so they can be dispatched through the normal signal routing pipeline. These routes have low priority to avoid conflicting with explicit routes.

Returns a list of route tuples suitable for Routes.detect_conflicts/1.