ErisPulse-Cron

ErisPulse-Cron — это модуль планировщика задач в экосистеме ErisPulse, предоставляющий единый API для других модулей: поддерживает три типа задач — однократные, интервальные и по Cron-выражениям, передачу параметров обратного вызова, а также сохранение в SQLite (задачи не теряются при перезапуске).

Important

Cron не является встроенной функцией фреймворка ErisPulse, его необходимо установить отдельно:

epsdk install Cron

После установки доступ к интерфейсу осуществляется через sdk.Cron.

Функциональные возможности

Три типа планирования: однократные (once), интервальные (interval) и по Cron-выражениям (cron)
Передача параметров обратного вызова: при создании задачи передается callback_data, при срабатывании возвращается без изменений, что помогает идентифицировать источник задачи
Сохранение данных: задачи хранятся в SQLite (через sdk.storage), автоматически восстанавливаются после перезапуска фреймворка
Стратегия обработки пропущенных задач: немедленное срабатывание / пропуск / перепланирование, выбор стратегии возможен на уровне задачи
Управление задачами: приостановка, возобновление, отмена, ручное срабатывание, очистка просроченных задач
Интеграция с Dashboard: при установке ErisPulse-Dashboard автоматически регистрируется окно управления

Быстрый старт

from ErisPulse import sdk

# 1. Регистрация обработчика обратного вызова
@sdk.Cron.on_trigger
async def handle_trigger(info):
    data = info["callback_data"]
    print(f"Задача запущена: {info['task_id']}, данные: {data}")

# 2. Создание планируемой задачи
task_id = sdk.Cron.once(
    delay=60,
    callback_data={"type": "напоминание", "msg": "Пора пить воду"},
)

Обзор API

Создание задач

# Однократная задача: срабатывает через 600 секунд
sdk.Cron.once(delay=600, callback_data={"order_id": "123"}, label="Напоминание о просрочке заказа")

# Интервальная задача: срабатывает каждые 300 секунд, максимум 100 раз
sdk.Cron.interval(interval_seconds=300, callback_data={"monitor": "server-1"}, max_runs=100)

# Задача по Cron-выражению: каждый будний день в 9:30
sdk.Cron.cron(expression="30 9 * * 1-5", callback_data={"type": "ежедневный отчет"})

# Общие опциональные параметры: trigger_at (абсолютное время), delay (отсрочка до первого запуска), timezone,
# max_runs (0=бесконечно), label, source (имя модуля-создателя), missed_policy (стратегия обработки пропусков)

Часто используемые Cron-выражения: */5 * * * * (каждые 5 минут), 0 8 * * * (каждый день в 8 утра), 30 9 * * 1-5 (в 9:30 в будние дни), 0 0 1 * * (1-е число каждого месяца).

Обратный вызов

@sdk.Cron.on_trigger
async def my_handler(info):
    # info содержит task_id / task_type / callback_data / label / source /
    # run_count / max_runs / created_at / last_run / trigger_time
    ...

Поддерживается регистрация нескольких обработчиков, все они вызываются последовательно, ошибка одного обработчика не влияет на другие.

Управление задачами

sdk.Cron.cancel(task_id)                  # Отмена задачи
sdk.Cron.pause(task_id)                   # Приостановка задачи
sdk.Cron.resume(task_id)                  # Возобновление (reschedule=True пересчитывает следующее срабатывание)
await sdk.Cron.trigger_now(task_id)       # Ручное немедленное срабатывание (не влияет на план)
sdk.Cron.get_task(task_id)                # Получение информации о задаче
sdk.Cron.list_tasks(source="MyModule")    # Получение списка задач (поддержка фильтрации по source/status/task_type)
sdk.Cron.delete_task(task_id)             # Удаление записи задачи
sdk.Cron.cleanup()                        # Очистка задач, завершенных или отмененных более 7 дней назад

Стратегия обработки пропущенных задач (`missed_policy`)

После перезапуска фреймворка для задач, пропущенных по времени срабатывания:

Стратегия	Действие
`fire_immediately`	Срабатывает немедленно (по умолчанию)
`skip`	Пропускает текущее срабатывание, ждет следующего
`reschedule`	Перепланирование с текущего времени

Поведение при отключении модуля

Данные задач Cron являются постоянными: удаление или отключение модуля-создателя не приводит к удалению уже созданных задач. Однако обработчики обратного вызова, зарегистрированные этим модулем, будут удалены — благодаря системе принадлежности ([внешние очистительные хуки](../advanced/ownership.md#инструкция по использованию инструментальных модулей для управления обработчиками других модулей)), Cron автоматически отслеживает принадлежность обратных вызовов, и при отключении/удалении модуля его обработчики будут автоматически удалены, обеспечивая корректное удаление экземпляра модуля.

После перезагрузки модуля-создателя он может снова зарегистрировать on_trigger и восстановить прием срабатываний
Ненужные задачи можно удалить с помощью sdk.Cron.cancel(task_id) / delete_task(task_id)