定期実行

runlot.json に triggers を加えると、ワーカーの scheduled ハンドラが指定した時刻に動きます。

{
  "name": "my-app",
  "main": "src/index.ts",
  "triggers": { "crons": ["30 18 * * *"] }
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    return new Response("hello");
  },
  async scheduled(controller: ScheduledController, env: Env, ctx: ExecutionContext) {
    // controller.scheduledTime は現在時刻ではなく、この実行の**予定時刻**です。
    // controller.cron は発火した式です。
    await rebuild(env);
  },
};

runlot deploy は登録するスケジュールを表示します。動き出す前に確認してください。

定期実行 (UTC): 30 18 * * *

式

5 つのフィールドです。分 時 日 月 曜日、タイムゾーンは UTC です。

日曜日は 0 です (7 も受け付けます)。日と曜日の両方が指定されている場合、どちらか一方に一致すれば動きます — cron は元々そう動くので、0 0 1 * 1 は「毎月 1 日、または毎週月曜日」です。

式はデプロイ時に実際に解析します。文法が誤っているもの、または永遠に発火しないもの (0 0 30 2 * — 2 月 30 日) は、どのフィールドが問題かを添えて 400 で拒否します。受け入れて動かないスケジュールは、壊れたデプロイと見分けがつかないからです。

上限

上限を超えた実行は中止し、失敗として記録します。頻繁なスケジュールの予算を小さくしているのは意図的です — 費用がかかるのはスケジュールを 1 つ多く持つことではなく、2 分ごとにプロジェクトを起こすことです。

知っておくこと

時刻はおおよそです。 実行は指定した分、またはその後に始まります。正確な秒に依存するものは作らないでください。

前の実行が終わっていなければ次の回は飛ばします。 2 分ごとの処理が 3 分かかる場合、その間に来た回は飛ばしてログに残します。この規則がないと、レーンが 1 つしかないプロジェクトに処理が溜まり続けます。

大きく遅れた実行は捨てます。 しばらく配信されていなかった場合、遅れた分をすべて取り戻すのではなく、直近の 1 回だけ実行します。そうしないと 1 時間の停止が */2 * * * * を 30 回続けて発火させます。

停止中のプロジェクトは起こします。 プロジェクトはアイドル中プロセスを落とします（停止と再開）。スケジュールが先に起こしてから動きます。起動時間は実行に含まれるので、休んでいたプロジェクトの初回は数百ミリ秒余分にかかります。

コールド状態のプロジェクトは遅れます。 長く休むとデータがマシンの外へ移ることがあります（コールド状態と再開）。今のところスケジュールはそれを引き戻しません — 他の何かがプロジェクトを復帰させた後に動きます。そのプロジェクトに触れるのがスケジュールだけなら、1 時間以下の間隔にしてください。

確認する

成功・スキップ・失敗のいずれでも、実行ごとにプロジェクトのログに 1 行残ります。

runlot logs

[runlot] 定期実行 30 18 * * * が完了しました (1.2s)

ワーカーが scheduled をエクスポートしていない場合、実行は失敗として記録され、その理由も同じ場所に残ります。main なしで triggers だけを書いたデプロイは拒否します — 静的アセットだけのデプロイには呼ぶハンドラがありません。

変更・削除

スケジュールはコードと一緒に動きます。runlot.json を直してデプロイしてください。以前のバージョンに戻すと、そのバージョンのスケジュールにも戻ります。triggers を消してデプロイすれば止まります。

まだないもの

手動で 1 回動かす方法と、ログバッファを超える実行履歴はありません。任意のタイミングで始めたい処理は、ルートを 1 つ用意し runlot secret set で入れたトークンで保護してください。