スケジュールジョブ（Cron）

スケジュールジョブとは何ですか？

スケジュールジョブとは、FloopFloop が定期的なスケジュール（5 分ごと、 1 時間ごと、毎日深夜など、設定した内容）で呼び出す、プロジェクト内の 通常の HTTP ハンドラーです。典型的な用途: 取引所から市場データをポーリングする、 キャッシュを更新する、毎日のダイジェストメールを送信する、 戦略を評価してトレードを行う。

各実行は、プロジェクト内の /api/cron/* 配下のルートへの POST であり、作業を行う前に検証するプロジェクトスコープの ベアラートークンが含まれます。

ハンドラーの作成

ハンドラーは通常の Next.js POST ルートです。作業を行う前に、process.env.FLOOP_CRON_TOKEN に対してベアラートークンを検証します。 それ以外のリクエストには 401 を返す必要があります:

// src/app/api/cron/rebalance/route.ts
import { NextRequest, NextResponse } from "next/server";

export const dynamic = "force-dynamic";

export async function POST(request: NextRequest) {
  const expected = `Bearer ${process.env.FLOOP_CRON_TOKEN ?? ""}`;
  if (request.headers.get("authorization") !== expected) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  // Do your work here — query data, call APIs, etc.
  return NextResponse.json({ ok: true });
}

FLOOP_CRON_TOKEN 環境変数は FloopFloop によって管理されます。 ビルド時にプロジェクトのランタイムに組み込まれ、シークレット UI には表示されません。

ジョブの登録方法

スケジュールジョブはテンプレートによって宣言され、手動で追加するものではありません。 テンプレートはルートに floop.crons.json ファイルを同梱します:

{
  "jobs": [
    {
      "name": "evaluate-strategy",
      "cron": "*/5 * * * *",
      "path": "/api/cron/evaluate-strategy",
      "enabled": true
    }
  ]
}

最初のデプロイメントが成功した後、FloopFloop はこのマニフェストを読み取り、 プロジェクトのジョブを登録します。登録は冪等です。同じテンプレートを再デプロイしても、 ジョブが重複したり、実行履歴がリセットされたりすることはありません。

アプリが異なるスケジュールを必要とする場合は、チャットで FloopFloop に テンプレートの floop.crons.json を更新するよう依頼してください。 次のデプロイ後に新しいスケジュールが有効になります。

実行ステータス

各実行は ok、error、または timeout のステータスで 記録されます。ハンドラーから非 2xx の HTTP ステータスを返すと、 その実行がエラーとしてマークされます。レスポンスボディ（最大 500 文字）が デバッグのためのエラーメッセージとしてキャプチャされます。

制限 & 制約

• プロジェクトごとに 10 のスケジュールジョブ。 floop.crons.json で 10 を超えるエントリを宣言するテンプレートは、 登録時にオーバーフロー分が拒否されます。
• 最小間隔 1 分。 サブ分単位の cron 式は 登録時に拒否されます。
• 実行ごとに 30 秒のフェッチタイムアウト。 ハンドラーがそれより 長くかかる場合、ディスパッチャーは timeout を記録して次に進みます。
• プロジェクトがデプロイ済みでアクティブな間のみ実行されます。 新規作成されたプロジェクトと停止中のプロジェクトはサイレントにスキップされ、 再アクティブ化時に自動的に再開されます。
• パスは /api/cron/<name> に一致する必要があります。 この制限により、cron の実行が公開向けルートから分離されます。