ErisPulse-Cron

ErisPulse-Cron は ErisPulse エコシステムのスケジュールタスクモジュールです。他のモジュールに統一されたスケジュールタスク API を提供します。1回限りのスケジュール、間隔ループ、Cron 表現式の3種類のタスクタイプをサポートし、コールバックにパラメータを渡すことができます。SQLite を用いた永続化により、再起動してもタスクが失われることはありません。

Important

Cron は ErisPulse フレームワークの組み込み機能ではなく、個別にインストールする必要があります：

epsdk install Cron

インストール後は sdk.Cron を使ってすべてのインターフェースにアクセスできます。

機能速覧

3 種類のタイミング設定：1 回限り (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": "reminder", "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": "daily_report"})

# 一般的なオプションパラメータ：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 が含まれる
    ...

複数のハンドラを登録可能で、すべて順次実行され、1 つのハンドラの例外は他のハンドラに影響しない。

タスクの管理

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)                # 1 つのタスクを取得
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 のタスクデータは永続化されたアセットです。タスクを作成したモジュールがアンロードまたは無効化されても、既に作成されたタスクは削除されません。ただし、そのモジュールが登録したコールバックハンドルはクリーンアップされます。所有権システムに基づく外部クリーンアップフックにより、Cron が他のモジュールのコールバックを管理する場合、自動的に所有者を記録します。その他のモジュールがアンロードまたは無効化された際に、そのコールバックハンドルは自動的に破棄され、他のモジュールのインスタンスが正常にリサイクルされることが保証されます。

タスク作成元のモジュールが再ロードされた後、on_trigger を再び実行することで、再びトリガーを受け取ることができます。
使用しなくなったタスクは sdk.Cron.cancel(task_id) / delete_task(task_id) を使用してクリーンアップできます。